This page last changed on Oct 11, 2010 by shawse.

Confluence System Administrators or Space Administrators can customise the PDF exports for individual Spaces using a PDF Stylesheet.

The PDF export feature enables you to customise the Look and Feel of PDF exports for:

  • Page and margin sizes
  • Headers and footers, each with customisable content such as page numbering
  • A customisable title page, which can incorporate images
  • Built-in support for table of contents with page numbering

On this page:

Before You Start

  1. Most PDF Stylesheet customisations are created using a combination of HTML and CSS (Cascading Style Sheets). So you should be comfortable with these technologies before implementing any customisations you require.
  2. PDF customisations are unique to each Space.
  3. There two areas that control Confluence custom PDF exports – the PDF Layout and the PDF Stylesheet). You will need to visit each of these areas to ensure your PDF exports are customised to your requirements.
  4. The PDF Layout defines the title page, and headers and footers.
  5. The PDF Stylesheet defines the page size and margins, font, colour, list numbering, and all other style export features.

Customising the PDF Layout

To customise the PDF Layout,

  1. While you are logged in as a System Administrator or Space Administrator, navigate to the Space for which you would like to customise the PDF Layout.
  2. From within the required Space, select the 'Browse' menu, then select 'Space Admin'.
  3. From the 'Look and Feel' area of the left-hand panel, select 'PDF Layout' to enable modifications to:
    • PDF Space Export Title Page - containing custom HTML that generates the exported title page.
    • PDF Space Export Header - containing custom HTML that generates headers throughout the exported content.
    • PDF Space Export Footer - containing custom HTML that generates footers throughout the exported content.
  4. Click the 'Edit' button to enable an editable text box for each of these three sections.
  5. Enter your customisations into each text box as required and click 'Save'.

Customising the PDF Stylesheet

To customise the PDF Stylesheet,

  1. While you are logged in as a System Administrator or Space Administrator, navigate to the Space for which you would like to customise the PDF Layout.
  2. From within the required Space, select the 'Browse' menu, then select 'Space Admin'.
  3. Click 'PDF Stylesheet' in the left-hand panel. The main PDF Export Stylesheet section on the right displays the current contents of your PDF Stylesheet customisations, which contains all CSS rule customisations applied to the pages in the space.
  4. Click the 'Edit' button to enable modifications to your PDF Stylesheet.
  5. Enter your customisations into the text box as required and click 'Save'.
Basic and Advanced Customisations
  • The Basic Customisations section below provides examples of typical customisations that can be added to your PDF Stylesheet. Once you are familiar with the implementation of basic PDF stylesheet customisations, you may wish to try out some Advanced Customisations.

Default Settings

  • If no PDF customisations are defined on the PDF Stylesheet screen, the PDF Stylesheet feature's default CSS rules will be applied to your PDF exports. By default, these exports do not display a title page, header or footer.
  • To get you started, you can download the PDF Stylesheet's default CSS rules, confluencedefaultpdf.css. Any rule defined in this file can be customised and added to the PDF Export Stylesheet section.
  • You can also make further CSS customisations as required. This means you can override any default CSS rule by redefining it in the PDF Export Stylesheet section with your own customisations.


PDF Export Methods

  • There are two PDF export methods.
    • Single pages via the 'Tools' menu -> 'Export to PDF' function on a page or blog post ('single page exports')
    • One or more pages in a space via the 'Advanced' view ('space exports')
    • You can visit the topic, Confluence to PDF for more detail on these methods.
  • When exporting a Space, all your customisations apply — including those made to your 'PDF Export Stylesheet', 'Title Page', 'Header' and 'Footer'.
  • However, only the 'PDF Export Stylesheet' customisations apply to single page exports.
  • To make your 'PDF Export Header' and 'Footer' customisations apply to a single page exported to PDF, either:
    • use the 'space export' method to export that single page only, or
    • if your header and footer customisations contain only text, follow the appropriate customisations provided in the Advanced PDF Stylesheet Customisations topic.

Basic Customisations

Page Customisations

Modifications to page and margin sizes are made in the @page CSS rule.

To make changes to this rule, you would implement the following type of code in the 'PDF Export Stylesheet' of the PDF Stylesheet.

@page
{
/*Page specific styles (that is, customisations of properties) go here*/
}

Customising the Page Size

The default page size is based on the locale of your Confluence server. Hence, if this server was located in the US, the default paper size of your PDF export would be US Letter size (8.5 inches wide by 11 inches long). If the server was located in Australia, the default paper size would be A4 (210 mm wide by 297 mm high).

To modify the page size to A4, add a size property to the top of the rule like this:

@page
{
/*The A4 paper size is 210 mm wide by 297 mm high*/
size: 210mm 297mm;
}

More information about paper sizes can be found on Wikipedia.

Customising the Page Margins

To add a margin of 15 mm to a paper size of A4, your CSS @page rule would look like this:

@page
{
size: 210mm 297mm;
margin: 15mm;
}

Customising the Table of Contents

By default, a table of contents will be generated after the title page, or at the beginning of the document if the 'PDF Space Export Title Page' (of the PDF Layout) is not defined. The look and layout of the table of contents is completely customisable by defining the appropriate CSS rules in the 'PDF Export Stylesheet'.

For details about the CSS rules governing the default styles applied to the table of contents output in PDF exports, download the default CSS rules (from the link above) and examine the specific rules with toc in its name.

Disabling the Table of Contents

To prevent the table of contents being generated in your exported PDF document, add the div.toc rule to the 'PDF Export Stylesheet' section of the PDF Stylesheet and set its display property to none:

div.toc
{
display: none;
}

Change the Leader Character

The leader character is used to visually link the name of a heading in the table of contents list with its page number, which is usually aligned to the page's right-hand margin. By default, the leader character is the '.' (dot) character. However, it can be changed by customising the leader character CSS rule span.toclead:before and adding this to the 'PDF Export Stylesheet' section of the PDF Stylesheet.

To change this to a solid line, modify this CSS rule accordingly:

span.toclead:before
{
content: leader(solid);
}

To change this it to spaces (that is, blank space), modify this CSS rule to:

span.toclead:before
{
content: leader(space);
}

Be aware that using a space as a leader character can make the table of contents list difficult to read.

Adding a Title Page to PDF-Exported Space or Subsection

You can create a title or cover page for an PDF-exported space or subsection using XHTML. Use the 'PDF Space Export Title Page' section of the PDF Layout to do this. The following XHTML code example uses an inline CSS rule to generate a title page.

<div class="fsTitlePage" style="margin-left:auto;margin-top:75mm;margin-right:auto;">
<img src="/download/attachments/12345/titlepage.png"/>
</div>

In the example above, an image called 'titlepage.png' will be centred in the middle of the page. This image is attached to a Confluence page and is referenced via its relative URL (that is, without the Confluence site's base URL component).

You can obtain the URL of an image attached to a Confluence page by viewing the list of attachments on that page and moving your mouse over the attachment's name. The URL of the image should appear in your browser's status bar or you can copy the link. Once you have this link, paste it into the appropriate src="" attribute within your PDF stylesheet and remove the first part of the URL up to the /download/... part.

Adding Headers and Footers

Headers and footers can be added to a PDF-exported space or subsection also using XHTML. Use the 'PDF Space Export Header' and 'PDF Space Export Footer' sections of the PDF Layout to create a custom header and footer, respectively. For simple headers and footers, plain text is sufficient. The following example added to a header or footer will create a simple copyright notice.

Copyright © 2009, Atlassian Pty Ltd.

Adding page numbering to a header or footer

To add page numbering to your documentation, you need to combine some customised XHTML in the header or footer along with some customised CSS in the 'PDF Export Stylesheet'.

First, create a header or footer with an empty span element and give it a unique id, for example pageNum (although this could be anything). This is the page number 'place holder' in your exported PDF document.

<span id="pageNum"/>

Next, create the following CSS selector rule for this empty span and add it to the 'PDF Export Stylesheet':

#pageNum:before
{
content: counter(page);
}

This will add a page number to your header or footer.

Analysing this CSS selector rule in more detail, the #pageNum selects the XHTML element with the specified id of "pageNum", which is the span element we created for the header or footer. The :before part of the selector is a 'pseudo class' that allows the insertion of content before the span element is processed. The counter(page) is a function that returns the current page number as its content. Finally, the content property inside the rule tells the CSS processor that dynamic content (that is, an incrementing page number) is to be inserted before the span tag.

General Formatting

You can also use the stylesheet to customise the output of just about anything else that will influence the look and feel of the final document. This includes fonts, tables, line spacing, macros, etc. The export engine works directly from the HTML output produced by Confluence. Therefore, the first step in customising something would be to find a selector for the HTML element produced by Confluence or the Confluence macro. Next you would add a CSS rule to the 'PDF Export Stylesheet' and your customisation would appear in the PDF export.

RELATED TOPICS

Advanced PDF Stylesheet Customisations


Document generated by Confluence on Oct 12, 2010 20:44